home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1995 February: Tool Chest / Dev.CD Feb 95 / Dev.CD Feb 95.toast / Sample Code / Newton Sample Code 1.2 / Miscellaneous / Signatures Appendix / Signatures Appendix
Encoding:
Text File  |  1993-10-17  |  17.7 KB  |  106 lines  |  [ONLN/HLX2]
  1. Newton Signature Guidelines
  2.  
  3.  
  4. To avoid name conflicts among Newton applications we are having developers register a single signature. You do not need to register individual applications. Once you have a signature, the guidelines below explain how to ensure the various global symbols and string your application uses will be unique.
  5.  
  6. Signature
  7.  
  8. Example: PIEDTS
  9. Signatures are an arbitrary sequence of approximately 4 to 10 characters (colons and vertical bars are not allowed, case is not significant).
  10.  
  11. Application Name
  12.  
  13. Example: 
  14. Llama
  15. This is the string displayed under your application's icon in the Extras drawer. This symbol does not have to be unique. So it would be possible for there to be two applications named "Chess" on the market. Presumably, their icons would distinguish them if they were both installed.
  16.  
  17. Application Symbol
  18.  
  19. Example: 
  20. '|Llama:PIEDTS|
  21. The appSymbol is formed by concatentating the application name, a colon, and the registered signature. This symbol is not normally visible to the end user. It is used to uniquely identify an application to the root view. Note: since appSymbols contain a colon, they have to be enclosed in vertical bars where they appear explicitly in NewstonScript code 
  22.  
  23. Package Name
  24.  
  25. Example:
  26. Llama:PIEDTS
  27. The package name is simply a string version of the appSymbol. The package name, is visible to the user in the pop up menu for removing software. Package names are limited to 26 characters, so this places a practical limit on the combined length of application names and signatures.
  28.  
  29. Predefined Constants
  30.  
  31. It is suggested that you define constants for your appSymbol and package name in your "Project Data" file: Example:
  32. constant kAppSymbol := '|Llama:PIEDTS|;
  33. constant kPackageName := "Llama:PIEDTS";
  34.  Use these constants throughout your code instead of hard coding in values. This will make it easier to maintain your code. All you have to do is keep your constant definitions consistent with the values in NTK's Settings... dialog. A future version of NTK may automatically define these constants for you.
  35. For the remaining examples we will assume the above constant definitions are in effect.
  36.  
  37. Soup Names
  38.  
  39. Examples:
  40. Llama:PIEDTS
  41. kPackageName
  42. soup1:Llama:PIEDTS
  43. soup2 & kPackageName
  44. The soups your application creates need to have unique names. You can use your package name directly or along with a colon as a suffix to a descriptive soup name. Soup names are not normally visible to the user. They are displayed to users by Newton Connection.
  45.  
  46. System Soup Tag
  47.  
  48. Example: {tag: kPackageName, firstName: "Reg"} Applications are expected to store their preferences data in the system soup. Each application is supposed to create a single soup entry with a unique tag slot and other application specific slots. Use your package name as your tag. This tag is not normally visible to the end user. However, if utility software is written to "clean up" the System soup, this tag may be used to prompt the user asking whether or not to delete an entry.
  49.  
  50. Additional Soup Fields
  51.  
  52. Example: 
  53. entry.(kAppSymbol) := { <AppSpecificData> }; 
  54. Applications are encouraged to utilize existing soups, like the Names soup. If applications needs to store their own data in entries of an existing soup, they should create a single slot using their appSymbol as the slot name.
  55.  
  56. Routing Formats
  57.  
  58. Examples: 
  59. GetRoot().('|fmt1:Llama:PIEDTS|) := { <Fmt Frame> };
  60. GetRoot().(Intern("fmt2:" & kPackageName) := { <Fmt Frame> }; 
  61. Applications need to store their formatting frames in the root view. Each formatting frame should be given a name and stored in the root view in a slot whose name is the format's name concatenated with a colon and the appSymbol.
  62.  
  63. Global Variables
  64.  
  65. Example: 
  66. GetGlobals().(kAppSymbol) := <AppSpecificData>; 
  67. Although the use of system wide global variables is strongly discouraged, it's sometimes necessary to use them. For this purpose, your application should create a single repository for global data by adding a slot to the global's frame using its appSymbol as the slot name.
  68.  
  69. HowToRegister
  70.  
  71.  To register your signature, please send the following information to
  72. PIESYSOP on AppleLink
  73. or
  74. PIESYSOP, MS/305-2A, 20525 Mariani Ave, Cupertino, CA 95014
  75. Name:
  76. Contact Person:
  77. Mailing Address:
  78. Phone:
  79. Email Address:
  80. Desired Signature 1st choice:
  81. Desired Signature 2nd choice:
  82.  
  83. Change History
  84.  
  85. 10/8/93    jp    New appendix today.
  86. Ædˇ ˇˇˇˇd
  87. ˇ·ˇ‚7Ç, Palatino
  88.     3,. Ã+ú#    APPENDIX Vø)sC
  89. 4⁄ú˙(,     Helvetica(‡ú    Signature
  91. Ù(‡C-1
  92. (ÔúAlpha Draft 1.1, Preliminaryg)[. ©s0)    1993∞) µÄ)Apple Computerƒ)6, Inc. ©ê)10/1ʇ)
  93. 1/93
  94. vZ£(4vZ£( ûZû(
  95. ˇ·ˇ‚7Ç
  96. ˇˇ¬òˇ◊°dONLNd\úuO(núNewton Signatursh°dONLNd\Ou—)≥ e Guidelinesˇˇˇˇˇˇπh)»C
  98. °dONLNd®ú¥¢(±úTµ¿°dONLNd®°¥ı)o avoid name confl˛°dONLNd1®ı¥ü)T$icts among Newton applications we ar“@°dONLNdU®ü¥˛)™e having developers rO‡°dONLNdj®ˇ¥&)`
  99. egister a °dONLNdtµú¡›(æúsingle signaturÃ@°dONLNdɵ›¡Ê)Ae. h@°dONLNdܵÁ¡Ì)
  100. Y(¿°dONLNdáµÌ¡A)ou do not need to r= °dONLNdöµA¡)T1egister individual applications. Once you have a °dONLNdÀ¬úŒ¿(Àúsignatur`°dONLNd”¬¡ŒÜ)%,e, the guidelines below explain how to ensur^†°dONLNdˇ¬ÜŒ)≈!e the various global symbols and °dONLNd œú€[(ÿú,string your application uses will be unique.
  101. ‚Z˝(4„Z˝(
  102. 
  103. Z(4Z( Z.
  104. ˇ·ˇ‚7Ç
  105. ˇˇ©ˇÆ°dONLNdN˙Z
  106. ó(ZSignatur∂Ô°dONLNdV˙ó
  107. û)=eˇˇˇˇˇˇ»(C
  109. °dONLNdYú*Í('úExample: PIEDTS°dONLNdi0ú<¡*Signatur °dONLNdq0¬<÷)&es arb¿°dONLNdv0÷<_)e an arbitrary sequence of appr•Ä°dONLNdï0_<)â)oximately 4 to 10 characters (colons and °dONLNdæ=úI›(Fúvertical bars ar‚ °dONLNdŒ=›Ih)A!e not allowed, case is not signifiÿ °dONLNd=iIÅ)åcant).
  110. PZk(4QZk(
  111. {ZÉ(4|ZÉ( }Z}.
  112. ˇ·ˇ‚7Ç
  113. ˇˇ©ˇÆ°dONLNd¯hZ{fl(vZApplication Nameˇˇˇˇˇˇ»(vC
  115. °dONLNd
  116. åúò«(ïú    Example: ,
  117. Courier.°dONLNd£úØ∫*Llama.°dONLNd∂ú¬Ù*OThis is the string displayed under your application's icon in the Extras drawer˝ °dONLNdi∂Û¬
  118. (øÛ. This °dONLNdp√úœƒ(ÃúCsymbol does not have to be unique. So it would be possible for ther‡°dONLNd≥√≈œ˜(Ã≈ e to be two °dONLNdø–ú‹f(Ÿú,applications named "Chess" on the market. Prj°dONLNdΖf‹ê) esumably/ °dONLNdÛ–ê‹)* , their icons would distinguish °dONLNd›úȉ(Êúthem if they wer?¿°dONLNd#›ÂÈ+)Ie both installed.
  119. Z (4ÒZ (
  120. Z#(4Z#( Z.
  121. ˇ·ˇ‚7Ç
  122. ˇˇ©ˇÆ°dONLNd6ZÈ(ZApplication Symbolˇˇˇˇˇˇ»(C
  124. °dONLNdJ,ú8«(5ú    Example: .°dONLNdTCúOˆ*'|Llama:PIEDTS|.°dONLNddVúb *QThe appSymbol is formed by concatentating the application name, a colon, and the °dONLNdµcúoü*
  125. rE°dONLNd∂c†oΩ)egisterî °dONLNdΩcΩoÔ) ed signatur燰dONLNd»cÔoÿ)26e. This symbol is not normally visible to the end user
  126. @°dONLNd˛cÿo)È. It is used to °dONLNdpú|L(yú)uniquely identify an application to the r±†°dONLNd7pL|r)∞oot view#@°dONLNd?pr|)&#. Note: since appSymbols contain a °dONLNdb}úâÇ(Üú5colon, they have to be enclosed in vertical bars wherÂ@°dONLNdó}Çâ˜)Êe they appear explicitly in °dONLNd≥äúñ˜(ìúNewstonScript code 
  127. ^ÇZ4`&}Uˇˇˇˇˇˇ
  128.     (f&
  129. Figure C-0*    T)able B-0ˇ˙dˇ ˇˇˇˇd
  130. ˇ·ˇ‚7Ç
  131. 4<\
  132. , Palatino
  133. &e.3+~"    APPENDIX ‡Ò)CC,     Helvetica
  134.     ˇˇ—ÚˇÆ(@~Newton Signature Guidelines4⁄<˙
  135. 
  137. (‡<C-2
  138.     )B Package Name
  139. *Alpha Draft 1.1 Preliminaryu0)Y. ©ÅP)    1993–) √†)Apple Computer”)6, Inc. ∑∞)10/1ı)
  140. 1/934^<¿
  141. 
  142. ^<x
  143. 4^<x
  144. 
  145. à<ê
  146. 4â<ê
  147.  ä<ä
  148. ˇ·ˇ‚7Ç
  149. ˇˇ©ˇÆ°dONLNdu<àß(É< Package Nameˇˇˇˇˇˇ»(ɲC
  151. °dONLNdô~•ß(¢~Example:,
  152. Courier.°dONLNd∞~ºΔ* Llama:PIEDTS.°dONLNd$√~œ˘*SThe package name is simply a string version of the appSymbol. The package name, is °dONLNdw–~‹;*
  153. ,visible to the user in the pop up menu for rÄ°dONLNd£–<‹á)æemoving softwar˚Ä°dONLNd≤–Ü‹fi)Je. Package names aró‡°dONLNd≈–fl‹)Y
  154. e limited °dONLNdœ›~Ȉ(Ê~Yto 26 characters, so this places a practical limit on the combined length of application °dONLNd(Í~ˆ’*
  155. names and signatur≠Ä°dONLNd:Í’ˆ‡)Wes.
  156. ˝<
  157. 4˛<
  158. 
  159. (<0
  160. 4)<0
  161.  *<*
  162. ˇ·ˇ‚7Ç
  163. ˇˇ©ˇÆ°dONLNd?<(L(#<PrÄ°dONLNdAL(n)edefiˇ°dONLNdFp(◊)$
  164. ned Constantsˇˇˇˇˇˇ»(#˛C
  166. °dONLNdU9~E¯(B~It is suggested that you defi´°dONLNdr9¯E)z9ne constants for your appSymbol and package name in your °dONLNd´F~Rã(O~"Pr°dONLNdÆFåRƒ)
  167. oject Data" fi@°dONLNdºFƒR˘)8 le: Example:.°dONLNd…]~ih(f~'constant kAppSymbol := '|Llama:PIEDTS|;°dONLNdÒk~wn*(constant kPackageName := "Llama:PIEDTS";.°dONLNdÉ~èÊ* Use these constants thr뇰dONLNd2ÉÊèy)h oughout your code instead of harı¿°dONLNdRÉyè¯)ìd coding in values. This will °dONLNdpê~ú$(ô~&make it easier to maintain your code. /†°dONLNdñê$úŸ)¶)All you have to do is keep your constant °dONLNdøù~©é(¶~defir °dONLNd√ùè©ú)@nitions consistent with the values in NTK's Settings... dialog. √¿°dONLNdùú©£(¶úA˛`°dONLNdù£©º) futurÁ‡°dONLNd
  168. ùº©Ò)
  169. e version of °dONLNd™~∂¸(≥~NTK may automatically defidONLNd1™¸∂q)~ne these constants for you.°dONLNdMº~»£(≈~    For the r†°dONLNdVº§»©)&7emaining examples we will assume the above constant defiGÄ°dONLNd麩»“(≈©
  170. nitions arÙ‡°dONLNdòº“»Ï))e in efh °dONLNdüºÌ»ˇ)fect.
  171. œ<Í
  172. 4–<Í
  173. 
  174. ˙<
  175. 4˚<
  176.  ¸<¸
  177. ˇ·ˇ‚7Ç
  178. ˇˇ©ˇÆ°dONLNd¶Á<˙ó(ı<
  179. Soup Namesˇˇˇˇˇˇ»(ı˛C
  181. °dONLNd≤ ~´(~    Examples:.°dONLNdº"~.Δ* Llama:PIEDTS°dONLNd…0~<Δ* kPackageName°dONLNd÷>~JÍ*soup1:Llama:PIEDTS°dONLNdÈL~Xˆ*soup2 & kPackageName.°dONLNd˛d~p*The soups your application cr°dONLNddpò)Ñ!eates need to have unique names. ‘@°dONLNd<dòpû)ñYî¿°dONLNd=dûpÊ)ou can use your °dONLNdMq~}Ã(z~package name dir`°dONLNd]qÕ}e)O$ectly or along with a colon as a suf< °dONLNdÅqe}k)òfiH‡°dONLNdÉqk})#x to a descriptive soup name. Soup °dONLNd¶~~ä¶(á~names arq°dONLNdÆ~¶ä7)("e not normally visible to the user˜ °dONLNd–~6ä\)ê    . They ará°dONLNdŸ~]äÎ)'e displayed to users by Newton °dONLNd¯ã~ó≥(î~ Connection.ˇdˇ ˇˇˇˇd
  182. ˇ·ˇ‚7Ç
  183. 4Z\(, Palatino
  184. &e.3+ú"    APPENDIX ‡Ò)CC,     Helvetica
  185.     ˇˇ—ÚˇÆ(@úNewton Signature Guidelines4⁄ú˙((‡ú System Soup Z¿)8T⁄¿)ag
  187. Ù(‡C-3
  188. (ÔúAlpha Draft 1.1, Preliminaryg)[. ©s0)    1993∞) µÄ)Apple Computerƒ)6, Inc. ©ê)10/1ʇ)
  189. 1/934^Z¿(
  190. ^Zx(4^Zx(
  191. àZê(4âZê( äZä.
  192. ˇ·ˇ‚7Ç
  193. ˇˇ©ˇÆ°dONLNduZàƒ(ÉZ
  194. System Soup Tl°dONLNd
  195. uƒà’)jagˇˇˇˇˇˇ»(ÉC
  197. °dONLNdôú•-(¢úExample: {tag: kPackageName, fi\°dONLNd0ô.•w)írstName: "Reg"} °Ä°dONLNd@ôw•ª)IApplications ar°†°dONLNdOôª•)De expected to stor≥°dONLNdaô•&)Me their °dONLNdi¶ú≤•(ØúprG °dONLNdk¶¶≤∂)
  198. eferÛ@°dONLNdo¶∂≤‘)Aences data in the system soup. Each application is supposed to cr¶@°dONLNd∞¶’≤%(Ø’eate a single soup °dONLNd√≥úøñ(ºú9entry with a unique tag slot and other application specifi„`°dONLNd˝≥ñø")˙c slots. Use your package name °dONLNd¿úÃû(…ú=as your tag. This tag is not normally visible to the end useréÄ°dONLNdY¿ûÃÃ(…û    . However °dONLNdb¿ÃÃ)., if utility softwarê@°dONLNdv¿Ã)Le °dONLNdxÕúŸ√(÷úDis written to "clean up" the System soup, this tag may be used to prÉ °dONLNdºÕ√Ÿ"(÷√ompt the user asking °dONLNd—⁄úÊ-(„ú!whether or not to delete an entry£`°dONLNdÚ⁄,Ê.)ê.
  199. ÌZ(4ÓZ(
  200. Z (4Z ( Z.
  201. ˇ·ˇ‚7Ç
  202. ˇˇ©ˇÆ°dONLNdıZ(ZAdditional Soup Fieldsˇˇˇˇˇˇ»(C
  204. °dONLNd
  205. )ú5«(2ú    Example: ,
  206. Courier.°dONLNd@úL™*-entry.(kAppSymbol) := { <AppSpecificData> }; .°dONLNdESú_‡*Applications arÄ °dONLNdTS‡_Û)D@e encouraged to utilize existing soups, like the Names soup. If °dONLNdî`úl (iúapplications needs to stor#°dONLNdÆ`
  207. l)q=e their own data in entries of an existing soup, they should °dONLNdÎmúy§(vúcrµ@°dONLNdÌm§yü):eate a single slot using their appSymbol as the slot name.
  208. ÄZõ(4ÅZõ(
  209. ´Z≥(4¨Z≥( ≠Z≠.
  210. ˇ·ˇ‚7Ç
  211. ˇˇ©ˇÆ°dONLNd)òZ´”(¶ZRouting Formatsˇˇˇˇˇˇ»(¶C
  213. °dONLNd:ºú»Ã(≈ú
  214. Examples: .°dONLNdE”úfl‘*4GetRoot().('|fmt1:Llama:PIEDTS|) := { <Fmt Frame> };°dONLNdz·úÌ*>GetRoot().(Intern("fmt2:" & kPackageName) := { <Fmt Frame> }; .°dONLNdπ˘ú *Applications need to stor≠@°dONLNd“˘ õ)o"e their formatting frames in the r
  215.  °dONLNdÙ˘ú¬)ëoot view{¿°dONLNd¸˘¡)%. Each formatting °dONLNdúH(ú%frame should be given a name and storì@°dONLNd3Ht)¨ ed in the rT¿°dONLNd>u)-%oot view in a slot whose name is the °dONLNdcú´(ú:format's name concatenated with a colon and the appSymbol.
  216. &ZA(4'ZA(
  217. QZY(4RZY( SZS.
  218. ˇ·ˇ‚7Ç
  219. ˇˇ©ˇÆ°dONLNdü>ZQô(LZGlobal Vœ∂°dONLNdß>òQŒ)>ariablesˇˇˇˇˇˇ»(LC
  221. °dONLNd±bún«(kú    Example: .°dONLNdªyúÖº*0GetGlobals().(kAppSymbol) := <AppSpecificData>; .°dONLNdÏåúòç*7Although the use of system wide global variables is str!Ä°dONLNd#åéò&)Ú"ongly discouraged, it's sometimes °dONLNdEôú•ƒ(¢úCnecessary to use them. For this purpose, your application should crο°dONLNdàôƒ•¸(¢ƒeate a single °dONLNdñ¶ú≤ü(ØúrE°dONLNdó¶†≤)Xepository for global data by adding a slot to the global's frame using its appSymbol as °dONLNdÔ≥úøŸ(ºúthe slot name.ˇdˇ ˇˇˇˇd
  222. ˇ·ˇ‚7Ç
  223. 4<\
  224. , Palatino
  225. &e.3+~"    APPENDIX ‡Ò)CC,     Helvetica
  226.     ˇˇ—ÚˇÆ(@~Newton Signature Guidelines4⁄<˙
  227. 
  229. (‡<C-4
  230.     )BHowTˇp)    oRegister
  231. (Ô~Alpha Draft 1.1 Preliminaryu0)Y. ©ÅP)    1993–) √†)Apple Computer”)6, Inc. ∑∞)10/1ı)
  232. 1/934^<¿
  233. 
  234. ^<x
  235. 4^<x
  236. 
  237. à<ê
  238. 4â<ê
  239.  ä<ä
  240. ˇ·ˇ‚7Ç
  241. ˇˇ©ˇÆ°dONLNdu<àj(É<HowTû?°dONLNduià¨)-    oRegisterˇˇˇˇˇˇ»(ɲC
  243. °dONLNdô~•Ü(¢~ T5¿°dONLNdôÜ•ë)o r@°dONLNdôë•Ì) egister your signaturˇ¿°dONLNd)ôÌ•©)\+e, please send the following information to°dONLNdU´~∑¨(¥~PIESYSOPÊ¿°dONLNd]´¨∑º). on œ@°dONLNda´º∑Î)    AppleLink°dONLNdkΩ~…á(Δ~or°dONLNdnœ~€¨*PIESYSOP `°dONLNdvœ´€))-, MS/305-2A, 20525 Mariani U`°dONLNdëœ*€1)A1†°dONLNdíœ1€Å)ve, Cupertino, CAA@°dONLNd£œÅ€ú)P 95014°dONLNd™·~Ìõ(Í~Name:°dONLNd∞Û~ˇ√*Contact Person:°dONLNd¿~£*Mailing 0Ä°dONLNd»£∫)%AddrÙ@°dONLNdÃ∫…)ess:°dONLNd—~#ú( ~Phone:°dONLNdÿ)~5ö*Email b °dONLNdfi)ö5±)Addr%‡°dONLNd‚)≤5¡)ess:°dONLNdÁ;~Gï(D~DesirÒ@°dONLNdÏ;ïG») ed SignaturÌ¿°dONLNd˜;»G¸)3
  244. e 1st choice:°dONLNdM~Yï(V~DesirÒ@°dONLNd
  245. MïY») ed SignaturÌ¿°dONLNdM»Y)3
  246. e 2nd choice:
  247. `<{
  248. 4a<{
  249. 
  250. ã<ì
  251. 4å<ì
  252.  ç<ç
  253. ˇ·ˇ‚7Ç
  254. ˇˇ©ˇÆ°dONLNd$x<ãÆ(Ü<Change Historyˇˇˇˇˇˇ+¸(Ü˙19
  256. °dONLNd4ú~®£(•~10/8/93°dONLNd<ú¨®¥).jp°dONLNd?úæ®)New appendix todayÄ°dONLNdQú®)].ˇ